home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / Installer SDK Cornucopia 1.1.2 / Upgrader / Released / Upgrader 1.1.1 / Additional Plug-in Examples / Common Files / UpgraderPlugin.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-02-12  |  12.5 KB  |  325 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        UpgraderPlugin.h
  3.  
  4.     Contains:    All common function defintions and structures
  5.                 between the upgrader and the plugins
  6.  
  7.     Version:    Upgrader 1.1
  8.  
  9.     Copyright:    © 1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11. */
  12.  
  13. #ifndef __UPGRADERPLUGIN__
  14. #define __UPGRADERPLUGIN__
  15.  
  16. #ifndef REZ
  17. #include <AppleEvents.h>
  18. #include <Dialogs.h>
  19. #endif
  20.  
  21. #if defined(__MWERKS__)        // <30>
  22. #include <SetUpA4.h>
  23. #include <A4Stuff.h>
  24. #endif
  25.  
  26. // General Shell error numbers that may be returned to plugins
  27. #define kCouldNotFindPluginMsgNum                    1000
  28. #define kUnknownPlugInHandlerErr                    1001                
  29. #define kNoHighLevelEventsErr                        1002                
  30. #define    kCouldNotFindResourceMsgNum                    1003
  31. #define kMemoryErrorMsgNum                            1004    
  32. #define    kCantSaveDocumentErr                        1005        // PSSaveDoc cannot save the specified DocViewer object.
  33. #define    kForceRestartWarningMsgNum                    1006
  34. #define    kAppNotFoundMsgNum                            1007
  35. #define    kDocNotFoundMsgNum                            1008
  36. #define    kAppCouldNotBeLaunchUnknownProblemMsgNum    1009
  37. #define    kAppCouldNotBeLaunchNoEnoughMemoryMsgNum    1010
  38. #define    kAppCouldNotBeLaunchFileOpenMsgNum            1011
  39. #define    kRightDiskNameWrongDiskInsertedMsgNum        1012
  40. #define    kWrongDiskInsertedMsgNum                    1013
  41. #define    kFileNotFoundOnServerMsgNum                    1014
  42. #define kCantEjectCDDiskMsgNum                        1015
  43.  
  44. // Errors Returned by PSQuitShell
  45. #define kUserContinuingAfterRestartAlertMsgNum        1030
  46.  
  47. // Plugin sequence errors 
  48. #define kUnknownPluginNameErr                        1040        // <16> 
  49. #define kNextPluginSameAsCurrentErr                    1041        // <28>
  50.  
  51. // Global data manager errors
  52. #define kUnknownGlobalDataErr                        2000
  53. #define kGlobalDataOutOfMemErr                        2001
  54.  
  55. #define    kUnsupportedPrefsFormatErr                    2010
  56. #define    kNoPrefsErr                                    2011
  57.  
  58. // Panel manager errors                                                
  59. #define kPanelItemNotFoundInListErr                    2050                
  60. #define kCannotLoadNeededResourceErr                2051
  61. #define kNoDataAvailableForItemErr                    2052
  62. #define kInternalErr                                2053
  63. #define kNoGlobalPanelErr                            2054
  64. #define kItemTypeMismatchErr                        2055
  65. #define kCantFindTextRsrcErr                        2056
  66. #define kItemNotLocalisedErr                        2057
  67. #define    kCantChangePanelItemToSpecifiedTypeErr        2058
  68.  
  69. // Dialog IDs : these are needed by plugins to define there own private 'ners' resources
  70. #define    kStopOrContinueDLOGID                        506    // note, center main
  71. #define    kQuitOrContinueDLOGID                        507    // note, center main
  72. #define    kNoteOKDLOGID                                508    // note, center main
  73. #define    kRestartOrContinueDLOGID                    514    // note, center main
  74. #define    kInsertDiskDLOGID                            515    // disk swap icon, center main
  75. #define    kStopOKDLOGID                                519    // stop, center main
  76. #define    kSkipOrContinueDLOGID                        520    // caution, alert parent
  77. #define kStopDLOGID                                    600 // OK, center main *note kStopOKDLOGID
  78.                                                         // shows a continue button as well as OK 
  79. #define kStopAndQuitDLOGID                            526 // <27>
  80. #ifndef REZ
  81. #ifdef __cplusplus
  82. extern "C" {
  83. #endif
  84.  
  85. /* PSErrorAlert related constants */
  86. #define kEmptyString (ConstStr255Param)"\p"
  87.  
  88. // Constants that are used in PSErrorAlert to define the default button and the selected button
  89. #define kOKButtonIndex                            1
  90. // Skip or continue
  91. #define    kContinueNotSkipBtnIndex                   1
  92. #define    kSkipNotContinueBtnIndex                   2
  93. // Continue or Quit
  94. #define    kQuitButtonIndex                        1
  95. #define    kContinueNotQuitBtnIndex                 2
  96. // Continue or Restart
  97. #define    kRestartButtonIndex                         1
  98. #define    kContinueNotRestartBtnIndex                 2
  99. // yes or no
  100. #define    kYesButtonIndex                            1
  101. #define    kNoButtonIndex                            2
  102.  
  103. // constants to indicate to PSErrorAlert whether to look in the
  104. // plugins resource file for the error or in the Shell resource file
  105. #define kStandardShellError    true            // Tells PSErrorAlert to look in Shell for error
  106. #define kPluginError        false            // Tells PSErrorAlert to look in Plugin res fork for error
  107.  
  108. // constants for PSQuitShell
  109. #define kDontAllowUserToContinue    false
  110. #define kAllowUserToContinue        true
  111.  
  112. //------------------------------------------------------------------------------------------------------
  113. //    G L O B A L   D A T A   D E F I N I T I O N S <15>
  114. //------------------------------------------------------------------------------------------------------
  115. typedef    OSType            GlobalDataType;
  116. typedef    Ptr                GlobalDataPtr;
  117.  
  118. enum                                        // This is the list of global data types shared between plugin's
  119.                                             // NOTE. plugin's can store their own global data as well.
  120.     {
  121.     kTargetDiskVolRefNumDataType =    'trgt',    // The selected volume vRefNum as set by Target Selectin plugin (SInt16).
  122.     kForceRestartOnQuitDataType =     'rsrq'    // Global data identifier to singal to shell and plugins that a restart is required (Boolean).
  123.     };
  124.  
  125.  
  126. //------------------------------------------------------------------------------------------------------
  127. //    P L U G I N   D E F I N I T I O N S
  128. //------------------------------------------------------------------------------------------------------
  129. #define    kEventHandlerID            'ehID'
  130. #define    kTerminationHandlerID    'thID'
  131.  
  132. typedef OSErr             ShellErr;
  133. typedef    OSType            HandlerIDType;
  134. typedef SInt16             ResourceID;
  135.  
  136. enum    
  137.     {
  138.     kUseDefaultNextModuleName = 0
  139.     };
  140.  
  141. //------------------------------------------------------------------------------------------------------
  142. //    P A N E L  M A N A G E R  D E F I N I T I O N S
  143. //------------------------------------------------------------------------------------------------------
  144. typedef WindowPtr         PanelPtr;
  145.  
  146. #define    kGlobalPanel    (void *)0xFFFFFFFF    // Pass this constant to PSShowPanel/PSHidePanel if the current
  147.                                             // global panel is unknown (eg. when the plugin does not itself display
  148.                                             // a panel).
  149. #define    kHelpPanel      (void *)0xFFFFFFFE
  150.     
  151. enum                                        // Definitions for the 'inFlags' parameter to PSNewCustomPanel()
  152.     {
  153.     kGrowWindow     = 0x02,
  154.     kIsGlobal         = 0x04,
  155.     kHasGoAwayBox    = 0x10                    // <07>
  156.     };    
  157.  
  158. typedef    UInt8            DVFlags;
  159.  
  160. //  Type and  definitions for the panel item types
  161. typedef unsigned long        PanelItemType;
  162. typedef PanelItemType        DocViewerType;        // <31> subset of PanelItemType
  163. enum
  164.     {
  165.     kStyledTextType        = 'STXT',                // 'TEXT' and 'styl' pairs
  166.     kStyledStringType    = 'SSTR',                // 'STR#', index and 'finf'
  167.     kPICTType            = 'PICT',
  168.     kDocResType            = 'DOCV',                // 'TEXT', 'styl' and 'PICT's stored in resources
  169.     kDocFileType        = 'DOCF',                // SimpleText file will optional 'styl' and 'PICT' in resource fork.
  170.     kControlType        = 'CNTL',
  171.     kIconType            = 'ICON',
  172.     kUserItemType        = 'USER'                // User panel item for drawing custom items.
  173.     };
  174.  
  175. enum                                             // <28> Used in PSAlert
  176. {
  177.     kUpgraderFile = 0,
  178.     kClientDataFile,
  179.     kCurrentPluginResFile
  180. };
  181.  
  182. typedef short DocumentType;                        // Used in PSAlert
  183.  
  184. typedef Byte                DocLocationType;    // kReadFromResourceFile, kReadFromSimpleTextFile                    // <22>
  185. enum {                                                                                                                // <07>
  186.     kPrinterAvailableMask = 0x00000001,
  187.     kStandardFilePackageAvailableMask = 0x00000002
  188. };
  189.  
  190. typedef    unsigned long        EnvironmentType;                                                                        // <22>
  191. enum {                                                                                                                // <22>
  192.     kReadFromResourceFile = true,                // <25>
  193.     kReadFromSimpleTextFile = false
  194. };
  195.  
  196.  
  197. //  Type and bit definitions for the action panel item attribute
  198. typedef    UInt16            PanelActionType;
  199.  
  200. enum
  201.     {
  202.     kContinueButtonMask = 0x0001,
  203.     kGoBackButtonMask     = 0x0002,
  204.     kQuitButtonMask        = 0x0004,
  205.     kHelpButtonMask        = 0x0008,
  206.     kDefaultButtonMask    = 0x0010
  207.     };
  208.  
  209. typedef Handle PanelUserItemHandle;                // <31>
  210.  
  211.  
  212. // Build in 'finf' resource ID's for the fontInfo field of StyledStringDesc.
  213. enum
  214.     {
  215.     kUpgraderFonts    = 128,
  216.     kLargeTextStyle = 0,                        // <33>
  217.     kMediumTextStyle,
  218.     kSmallTextStyle,
  219.     kAlertTextStyle                                // <32>
  220.     };
  221.     
  222. enum {        // where the 'finf' is to be read from
  223.     kFontInfoInClientDataFile,
  224.     kFontInfoInPluginFile,
  225.     kFontInfoInShell,
  226.     kFontInfoInAnyFile
  227. };
  228.  
  229. // Constants to use with PSLaunchFile
  230. #define kLaunchAppInFront    true                // Tells PSLaunchFile to bring the launched application to the front
  231. #define kLaunchAppInBack    false                // Tells PSLaunchFile to leave the launched application in the back.
  232.  
  233. struct FontInfoRec {                            // <21>
  234.     short        font;
  235.     short        style;
  236.     short        size;
  237. };
  238. typedef struct FontInfoRec FontInfoRec, *FontInfoRecPtr;
  239.  
  240. /* Macros to customize Metrowerks code resource macros */
  241. // Call this Macro whenever control is swithched to the plugin
  242. #if defined(__MWERKS__)                                    // <30>
  243. #define    EnterPlugin()                            \
  244.         EnterCodeResource();
  245. #endif
  246.  
  247. // Call this Macro whenever control is from the plugin to the shell
  248. #if defined(__MWERKS__)                                    // <30>
  249. #define ExitPlugin()                            \
  250.         ExitCodeResource()
  251. #endif
  252.     
  253. extern     QDGlobals                 *gQDPtr;                // <30>
  254.  
  255.  
  256. /* PROTOTYPES */
  257.  
  258. // Global Data Manager calls
  259. extern ShellErr         PSSetGlobalData( GlobalDataType inGlobalDataType, GlobalDataPtr inGlobalDataPtr, Size inDataSize );
  260. extern ShellErr         PSGetGlobalData( GlobalDataType inGlobalDataType, GlobalDataPtr inGlobalDataPtr, 
  261.                                         Size inMaxDataSize, Size *outActualDataSize );
  262.  
  263. // Plugin management calls
  264. extern ShellErr         PSGoToPreviousPlugin( void );
  265. extern ShellErr         PSGoToNextPlugin( ResourceID inStrResID );
  266. extern ShellErr            PSQuitShell( Boolean canAllowUserToContinue );        // <03>
  267. extern ShellErr            PSRegisterHandler( HandlerIDType inHandlerType, UniversalProcPtr inHandlerProcPtr );
  268.  
  269. // Panel management calls
  270. extern ShellErr            PSSetupNewPanel( SInt16 inPanelItemsRsrcID, PanelPtr *outPanelPanelPtr );
  271. extern ShellErr            PSNewCustomPanel( short inPanelItemsRsrcID, DVFlags inFlags, PanelPtr *outPanelPanelPtr );
  272. extern ShellErr            PSUpdatePanel( PanelPtr inPanel );
  273. extern void                PSDisposePanel( PanelPtr inThePanel );
  274. extern ShellErr         PSShowPanel(PanelPtr inPanel );
  275. extern void                PSHidePanel( PanelPtr inPanel );
  276. extern Boolean            PSGetPanelItemHit( PanelPtr inPanel, EventRecord *inPanelEvent, short *outItemHit);
  277. extern ShellErr            PSSetPanelItem(PanelPtr inPanel, short inItemNumber, PanelItemType inItemType, Handle inItemHandle, Rect *inItemRect);
  278. extern ShellErr         PSGetPanelItem(PanelPtr inPanel, short inItemNumber, PanelItemType *outItemType, Handle *outItemHandle, Rect *outItemRect);
  279. extern void                PSSetPRefCon(PanelPtr inPanel, long inRefCon);
  280. extern long                PSGetPRefCon(PanelPtr inPanel);
  281. extern ShellErr            PSSetPanelItemAction(PanelPtr panel, short itemNumber, PanelActionType actionType);
  282.  
  283. extern TEHandle         PSNewStyledStringItem(Rect *inItemRect, short inSTRListRsrcID, short inStringListItem, short inFontNum, short inFontStyle, short inFontSize);
  284. extern TEHandle            PSNewStyledTextItem(Rect *inItemRect, short inTEXTRsrcID);
  285. extern PanelUserItemHandle PSNewUserItem(UserItemProcPtr inUserItem, Boolean transparent);
  286. extern Handle            PSNewDocViewerItem(PanelPtr inPanel, Rect *inItemRect, DocViewerType inDocViewerType, short inTextRsrcID, short inBasePICTRsrcID);
  287. extern ShellErr            PSActivatePanel(PanelPtr inPanel, Boolean shouldActivate);  
  288.                       
  289. // DocViewer item related calls
  290. extern ShellErr            PSHandleDocScroll(PanelPtr inPanel, Point localPt, short inDocItem);
  291. extern void                PSSaveDoc( PanelPtr inPanel, short inDocItem) ;
  292. extern ShellErr            PSPrintDoc( PanelPtr inPanel, short inDocItem );
  293.  
  294. // Standard help windows calls
  295. extern OSErr            PSSetupHelpWindow ( DocLocationType location, short resID, short basePICTResID, Str255 helpPanelTitleStr, PanelPtr *outHelpPanel );        // <28>
  296. extern void                PSDisplayHelpWindow ( PanelPtr inHelpPanel );                                                                                            // <28>
  297. extern void                PSCloseHelpWindow ( PanelPtr helpPanel );                                                                    // <22>
  298. extern Boolean            PSHandleHelpWindowEvent ( PanelPtr inHelpPanel, EventRecord *inEvent );                                        // <22>
  299.  
  300. // Utility calls
  301. extern OSErr            PSCheckEnvironment ( EnvironmentType *theEnvironment );                                                        // <22>
  302. extern Boolean            PSReadFontInfo ( short location, short inResID, short inFontItem, short *outFontFace, short *outFontStyle, short *outFontSize );    // <21>        // <29>
  303. extern Boolean            PSLaunchFile(SInt16 inAppFileRefRsrcID, SInt16 inDocFileRefRsrcID, AEDescList *inOptionalOpenParams, Boolean inLaunchAppInFront, ProcessSerialNumber *outApplicationPSN);
  304. extern SInt16             PSErrorAlert( SInt16 errNum, Boolean isStandardShellErr, ConstStr255Param p0, ConstStr255Param p1, ConstStr255Param p2, ConstStr255Param p3, SInt16 inDefaultButton, SInt16 inCancelButton );
  305. extern void             PSCollect(SInt16 inResListRsrcID);                                            // <19>
  306. extern SInt16             PSAlert(short DLOGID, DocumentType whichFileContainsDLOG, ConstStr255Param alertText, ConstStr255Param     p0, ConstStr255Param p1, ConstStr255Param p2, ConstStr255Param p3, SInt16 inDefaultButton, SInt16 inCancelButton );
  307.  
  308.     
  309. /* Prototypes for the 3 required plug-in handler routines */
  310. void        InitializePluginModule        (    void* inPSTable, 
  311.                                             SInt32 inRefCon, 
  312.                                             Boolean inEnterAtBeginning );
  313. Boolean        HandleEventForPluginModule    (    EventRecord *inEvent );
  314. void         TerminatePluginModule        (    void );
  315.  
  316. /* Macro so plugin main entry point conforms to ERS */
  317. #define     InitializePluginModule main                    // <30>    
  318.  
  319. void    SetupPlugin( void *shellFunctions );
  320.  
  321. #ifdef __cplusplus
  322. }
  323. #endif
  324. #endif                    //REZ                                                
  325. #endif